API Model for LeetCode Service

Understand the use of data entities and API endpoints for the LeetCode API service.

We'll cover the following

This lesson models the LeetCode API by discussing its base URL, the endpoints of various services, the data entities, and the messages exchanging these data entities to fulfill different user requests. The design considerations from the preceding lesson will inform our API modeling.

Base URL and API endpoints#

The following is the base URL of the LeetCode service:

Base URL for the LeetCode service
Base URL for the LeetCode service

We’ll use api.leetcode.com as the host URL for requesting distinct LeetCode services.

The endpoints for each operation are defined against the respective service in the following diagram. You can view the remaining endpoints by unfolding each service.

GET /v1.0/contest/leaderboard/{contestID} HTTP/1.1
GET /v1.0/contest/history HTTP/1.1
POST /v1.0/contest/submit HTTP/1.1
POST /v1.0/contest/register HTTP/1.1
Leaderboard
Check history
Submit code
Register contest
Discuss service
Interview service
Contest service
Problem service
User service
API endpoints for LeetCode service

Below, we discuss the endpoints of each service individually:

  • User service: The /register, /login, and /profile endpoints in user service handle user registration, login, and view profile requests, respectively.

  • Problem service: We list the most recently added problems using the /problems/{parameters} endpoint of the problem service. Parameters, such as difficulty level or sort by date, are optional. We can also search a topic by using the /problems?query endpoint, whereas query contains the topic name or category of problems. The user's solutions to the problems are evaluated, and results are shown directly using the /problems/evaluate endpoint.

  • Contest service: The contest service provides /register to register for a contest, /submit to submit the code for evaluation, /history to fetch the contests' history of a user, and /leaderboard to show the contest's standings.

Point to Ponder

Question

How does the interview service schedule the interviews?

Hide Answer

The interviewer creates/schedules an interview using the /schedule endpoint of the interview service. This endpoint further interacts with third-party services, such as Zoom, to schedule an interview. The following illustration depicts how interview service works:

The API gateway forwards the user’s request to create a meeting to the /schedule endpoint of the interview service. The interview service processes the data and further requests the Zoom service to create a meeting based on the information passed by the user.

The Zoom service schedules a meeting and responds with a joinLink to the interview service, which conveys the meeting information to the user. For more details on how the connection establishes, please read the Zoom API model.

Similarly, the different endpoints of the discuss service enable users to create, update, and delete a topic, comment on it, and search topics and comments created by other users.

Note: Some of the functionalities listed above have already been discussed in other design problems. Therefore, here we focus only on the endpoints related to LeetCode’s distinct features.

Message format for API endpoints#

This section discusses various data entities involved in performing different operations of the LeetCode service.

LeetCode data entities#

The LeetCode service uses the following data entities between the client and backend services:

Data entities to communicate with the LeetCode service

Let’s discuss the request and response format of endpoints of the LeetCode service.

Register contest#

The register contest endpoint registers a user’s participation in a contest. The request and response format for the operation is given below.

  • HTTP method: The create operation sends the user’s data to the backend service using the POST method.

  • Request format: The request format to register for a contest is defined below:

HTTP request format to register for a contest

  • Response format: A contest is registered by processing the request above to generate the following response:

Response format to register a contest

List problems#

The list problems endpoint fetches a list of problems based on the user's query from the problem service. The request and response format is defined below:

  • HTTP method: We will use the HTTP GET method to fetch data from backend services.

  • Request format: The following request format is used to fetch the list of problems. The parameters are optional. For example, if parameters are not passed in the difficultyLevel request, the response will contain a paginated list of the most recently added problems regardless of their difficultyLevel.

The HTTP request format to fetch problems

  • Response format: The user receives the following response if the request is successful:

The response to fetch problems

Submit code#

The submit code endpoint lets contestants submit their code alongside metadata. The contest service receives the information and processes it. The request and response formats are given below:

  • HTTP method: The HTTP POST method is used to perform the code submission operation.

  • Request format: The following request format is used to submit the code:

HTTP Request format to submit code

  • Response format: A successful processing of the request produces the following response:

Response format to submit code

Point to Ponder

Question

Why do we have a status code 202 Accepted instead of 200 or 201 in response to the submit code request?

Hide Answer

The 202 Accepted status code indicates that the request is accepted for processing. It’s possible that the processing will initiate now, later, or not at all.

For code submission in LeetCode, the processing of codes involves many other microservices, which need to process it according to a sequence. We send this response to let the clients know that their submission has been accepted for processing, and they will be notified in due time.

Note: A 202 status usually has a location (URL) included where the client can recheck the final status later on.

Failed requests#

The following errors can occur during the processing of a request by the LeetCode service:

Error Responses

Status code

Phrase

Description



4xx



Invalid Requests

The following reasons can make a request invalid:

  • Invalid parameters: 400
  • Forbidden request: 403
  • Not Found: 404

5xx

Internal Server Error

These status codes appear due to server's internal issues - 500

Summary#

The following table summarizes the operations, endpoints, data entities, and responses of all the subservices of LeetCode:

Service

Operations

Endpoints

Data Entities

Response

(Status Code, Body)

User

Register

POST /v1.0/users/register

name, username, email, password

201 Created, Yes

Login

POST /v1.0/users/login

username, email, password

200 OK, Yes

Profile

GET /v1.0/users/profile

userID

200 OK, Yes

Problem

List Problems

GET /v1.0/problems/{parameters}

Optional parameters

200 OK, Yes



Evaluate Code


POST /v1.0/problems/evaluate

userID, questionID, testCases, submittedCode, programmingLanguage

200 OK, Yes

Search Problem

GET /v1.0/problems?query

userID, topic

200 OK, Yes

Contest

Register Contest

POST /v1.0/contest/register

name, email, userID, contestID

201 Created, Yes


Submit Code


POST /v1.0/contest/submit

userID, questionID, testCases, submittedCode, programmingLanguage


202 Accepted, No

Check History

GET /v1.0/contest/history

userID

200 OK, Yes

Leaderboard

GET /v1.0/contest/leaderboard

contestID

200 OK, Yes



Interview


Schedule Interview



POST /v1.0/interview/schedule

userID, interviewerID, intervieweeID, interviewStartTime, interviewEndTime

201 Created, Yes

Discuss

Create Topic

POST /v1.0/discuss/topic

userID, topicText, dateCreated

201 Created, Yes


Update Topic


PUT /v1.0/discuss/topic

userID, topicID, topicText, dateCreated

200 OK, Yes

Delete Topic

DELETE /v1.0/discuss/topic

userID, topicID

200 OK, Yes




Comment




POST /v1.0/discuss/topic/comment

userID, topicID, commentID, commentText dateCreated, commentLink, threadID, replyingTo, pageToken



201 Created, No

Search Topic/Comment

GET /v1.0/problem?query

userID, topic/comment

200 OK, Yes

Point to Ponder

Question

While the /evaluate and /submit endpoints seem similar in terms of the data entities they use, their response code and behavior are different. What do you think differentiates the two?

Hide Answer

When users want to know whether the code is correct while practicing a programming problem, they interact with the /evaluate endpoint. This endpoint executes the code and returns the results directly to the end users, such as compile-time errors or successful execution with a status code of 200 OK.

Whereas, during a contest, when users attempt all the problems, they interact with the /submit endpoint to submit the codes. This endpoint accepts codes and responds with 202 Accepted, indicating that the codes will be processed later through different services in a sequence. The evaluation results will later be conveyed to the end users.

The next lesson will discuss response time and optimization techniques to achieve non-functional requirements.

LeetCode API Design Decisions

LeetCode API Design Evaluation and Latency Budget